Upstream User Guide and Technical Manual
Welcome
Summary
Welcome to the Upstream User Guide! Upstream is an intuitive and user-friendly R Shiny application designed to inform barrier culvert restoration prioritization in Western Washington. This guide serves as both a technical manual and a comprehensive overview of the app’s functionalities, including its core features: Explore, Suggest, Custom, and Learn.
In this guide, you’ll find detailed explanations of each feature:
Explore: Delve into our data and visualize culvert attributes across various spatial and ownership boundaries.
Suggest: Receive tailored restoration plans based on your preferences and budget constraint.
Custom: Create and assess the impact of your own set of restoration projects.
Learn: Learn about Upstream’s data, project team, and user support.
With helpful tips, step-by-step instructions, and links to related resources, this guide is your comprehensive companion in utilizing Upstream effectively and interpreting the results from the app.
To get started, select a tab above for detailed insights into each of Upstream’s unique features.
Static view of interactive map tool
Looking for Additional Information?
If you require more details or have specific questions, we’re here to help. Feel free to reach out to us for further assistance or any queries you might have.
Explore
Overview
The Explore feature is designed to visualize culvert attributes across various spatial and ownership boundaries.
Getting Started
Choose the ‘Explore’ tile on the Upstream landing page or select the the corresponding tab. This feature automatically displays a map of the WDFW fish passage inventory for western Washington, updated with each new version of Upstream. It filters out corrected barriers, natural barriers, and any barrier culverts situated upstream of natural barriers.
Interactive Map
The interactive map in the Explore feature is a key component for visualizing culvert data. Here’s how to navigate and use it:
Zoom for Details: At higher zoom levels, the map displays counts of culverts to manage the density of information. As you zoom in, individual culverts are revealed, allowing for more detailed examination.
Click for Information: Clicking on a culvert once it’s visible on the map brings up a callout with culvert data such as the WDFW site ID number, passability, potential fish species, and estimated habitat and construction cost.
Filtering for Focus: Utilize the dropdown menus to select culverts within specific WRIAs, HUC-12s, and ownership types. This tailors the map to show only the data relevant to your interests.
Map Call-Outs
Zoom into your area of interest and click on a culvert to access detailed information. The callouts provide insights into:
- The WDFW Site IDa
- Passability estimatesa
- Potential fish species a
- Total habitat upstream of a culvertb
- Habitat upstream of a culvert to next barrierb
- Estimated construction costb
- Ownership typea
- The number of culverts corrected downstream by WSDOTb
- The number of culverts corrected downstream by other than WSDOTb
- Weather WSDOT plans to correct that particular barrierb
- The date the culvert was surveyeda
a denotes variables from the WDFW inventory and b denotes Upstream variables.
Area, Subarea, and Ownership
Area
To refine the inventory data, use the dropdown menu to select Water Resource Inventory Areas (WRIAs) of interest. For multiple selections, ensure ‘All WRIAs’ is deselected. Similarly, selecting specific ownership types will filter the maps and figures accordingly.
Subarea
The Subarea selector allows for further specification and will auto populate with subareas contained within the selected Areas.
Ownership
The Ownership selector filters the culverts based on their ownership as defined in the WDFW inventory. This includes City, County, Federal, Private, State, Tribal, Other, Port, Drainage District, Irrigation District, and Unknown.
Select Variables For Plotting
This section allows you to plot variables as a histogram or scatterplot. For instance, to analyze the relationship between the cost of culvert repairs and the length of blocked habitat:
- Set Plot Type to “Scatterplot”.
- Choose “Cost” for the X-axis variable.
- Select “Full Habitat Length” for the Y-axis.
- Additionally, we can visualize a third variable with the fill color. Here we will select “Count of Downstream Barriers”.
Adjust the plot’s appearance using the jitter sliders to help visualize dots that are overlaid on top of each other.
Highlight Barriers
The highlight barriers field allows specific culverts to be selected by their ID from the WDFW barrier inventory. This will highlight them both on the map as well as in the plot.
Submit and Visualization
Click “Submit” to generate two outputs:
- An interactive map showcasing culverts within the selected area (outlined in dark blue), subarea, and ownership. Note that the highlighted culverts are outlined in bright, light blue. Clicking on the culverts in the map also will trigger a popup window displaying additional attributes.
- A clickable scatter plot illustrating the chosen characteristics. Again, if highlight barrier(s) is selected and barriers are added, then these will be circled as bright blue.
Note: The ‘Select Variable for Map’ and ‘Plot Fill Color’ options enhance the visualization of the selected variable on both the map and scatter plot.
Suggest
Overview
The Suggest feature returns a restoration plan that maximizes a flexible objective, given the users budget, project area, and other constraints.
Getting Started
To initiate the Suggest feature on the Upstream platform, simply select your project area, the culvert ownership types of interest, define your objective, and provide a budget. This process, accessible in the Suggest section, is intended to be flexible and user-friendly, allowing you to quickly set parameters for your a suggested habitat restoration plan.
Area, Subarea, and Ownership
In the Suggest feature, refining culverts based on Area, Subarea, and Ownership sets the benefit of any culvert outside the selection to zero. Note that a culvert outside the selected area, subarea or ownership could still end up in the suggested solution. This will happen if restoring culverts outside of the selection is required to achieve the greatest benefit within the solution. The tool will point this out.
Area
To refine the inventory data, use the dropdown menu to select Water Resource Inventory Areas (WRIAs) of interest. For multiple selections, ensure ‘All WRIAs’ is deselected. Similarly, selecting specific ownership types will filter the maps and figures accordingly.
Subarea
The Subarea selector allows for further specification and will auto populate with subareas contained within the selected Areas.
Ownership
The Ownership selector filters the culverts based on their ownership as defined in the WDFW inventory. This includes City, County, Federal, Private, State, Tribal, Other, Port, Drainage District, Irrigation District, and Unknown.
*For example we are choosing the Kennedy - Goldsborough WRIA with all HUC 12s and all ownership types.
Already Planned / Will Complete
In addition to spatial and administrative constraints, users can enhance their Suggest analysis through providing data and customizing the objective. The ‘Already Planned / Will Complete’ field allows users to input the IDs of culverts that have either been recently completed (but whose corrected status is not yet reflected in the app’s data) or are already planned and budgeted for repair separately. When you include these culverts, the analysis will not allocate any of your budget towards them. Instead, it will assume they are already fixed and passable, allowing the tool to suggest additional barriers for repair within your remaining budget.
The culverts marked as ‘Already Planned / Will Complete’ will be excluded from the estimated cost and habitat gains of a suggested plan, but their associated habitat will still be displayed on the map for informational purposes.
Note: If you don’t know the culvert id, but know their physical locations, simply navigate to those points on the map, click, and copy/paste the id from their call out into the Already Planned / Will Complete field.
Select Species
The ‘Select Species’ button allows users to tailor the analysis to specific fish species of interest. The species options are derived from the Washington Department of Fish and Wildlife (WDFW) fish passage inventory and include the five Pacific salmon species (Chinook, Coho, Chum, Pink, and Sockeye) as well as Steelhead. By selecting a species, you can focus the analysis on the habitat needs and passage barriers relevant to that particular species.
When a species is selected, the analysis adjusts to reflect the habitat suitability and passage requirements for that species. If a culvert does not provide habitat for the selected species the benefit of modifying or repairing that culvert is set to zero in the context of the selected species. This ensures that the analysis and subsequent recommendations are specifically targeted to improve conditions for the species of interest, allowing for more effective and targeted conservation efforts.
Habitat Quantity Definition
Habitat quantity is a critical metric in environmental assessment and can be quantified in terms of length, area, or volume. By default, length is used as the primary measure.
Note: For area and volume calculations, bankfull width and depth are utilized as outlined in Bieger et al. 2015.
Objective
The Objective feature in Upstream allows consideration of habitat quality. When selecting ‘Weighted Attributes’, the system incorporates various habitat quality metrics, building upon the chosen Habitat Quantity Metric.
This feature allows users to assign weights to different land use types within a 100-meter buffer surrounding the habitat. These land use categories, derived from the National Landcover Dataset, include urban, agricultural, and natural areas. This weighting system enables users to obtain suggested plans with more or less focus on particular habitat types (e.g. more weight on forested habitat). Note: Weights must sum to 1.
Additionally, the ‘Ideal Habitat Temperature’ option allows users to factor in temperature conditions, further refining the habitat quality analysis. For simplicity, August mean temperature is considered as it is a proxy for the max average monthly temperatures anadromous species are likely to encounter. The temperature values are taken from the NHDplusV2 and have been computed using a grid which combined the Parameter-elevation Regressions on Independent Slopes Model data PRISM for the period between 1971 and 2000 Documentation. Missing temperature values were interpolated using inverse distance weighting (IDW) with n.max = 10 while also including bank full width.
It’s important to note that temperature will act as a filter in the analysis. Users can set an ideal temperature range for the selected species, and the benefits of modifying or repairing a culvert will drop to zero if the temperature is outside this range.
Cost
In the Cost section of Upstream, users have the flexibility to input specific financial details for their projects. This feature is particularly useful for those who have precise cost information at their disposal.
- Default Modelled Cost Estimates: For users without specific cost data, Upstream offers a default option that utilizes modeled cost estimates. These estimates are based on a comprehensive analysis of regional data and provide a reliable approximation for project budgeting. The modeled estimates are continually updated to reflect current economic conditions and provide a robust starting point for users who do not have access to specific cost data.
Specifically, our default cost estimates were predicted from the model described in Van Deynze et al 2022. As predictions were made in 2019, we have adjusted the predictions for inflation to the year of the last Upstream release date. Further unknown costs are spatially interpolated using inverse distance weighting (IDW).
- Provide Mean Project Cost: Users can modify our default cost data in two ways. First, users can enter a design cost. Because our default cost estimates do not include design cost, the user-provided design costs will be added to our cost estimates.
Second, users can provide a mean construction costs, which will be used to rescale our cost estimates multiplicatively. For example, if the user-provided mean cost is twice as much as the mean of our cost estimate for the entire case area, our cost estimates will be multiplied by 2.
Enter Budget
Users must provide a budget in US dollars—such as 800000 in the example to the right.
For example, on the right we allow for Upstream to a suggest culvert restoration plan of all ownership types in all sub-areas within the Kennedy - Goldsborough WRIA. No further customization was made.
Note that the suggested solution will not exceed the provided budget. Therefore, it is important to check whether the solution is substantially changed by adding small amounts to the provided budget.
Submit
Without additional selections (see below), clicking “Submit” will provide two products:
- A map highlighting, in blue, barrier(s) that are estimated to unlock the most habitat for the user defined budget.
- A report, matching suggested projects on the map, that provides the total estimated habitat gains, by fish species (if known), along with estimated cost per barrier id within the plan.
Example
Now let’s consider prioritizing Chinook habitat, weighing urban habitat as .1, agricultural habitat as .2 and natural habitat as .7. The Already Planned / Will Complete will remain the same as in the previous example.
In the new map, we see that overall habitat length as shown by the thick blue lines has decreased given these priorities.
We also see this in the report as the Total Habitat decreased yet Chinook habitat did increase under these priorities.
Custom
Overview
The Custom feature on Upstream allows for detailed habitat restoration planning. It enables users to select specific culverts by ID, in addition to setting budget, project area, and ownership types. This feature is ideal for targeted restoration efforts.
Getting Started
To use Custom, start by choosing your project area, budget, and culvert ownership types, similar to the Suggest feature. The unique aspect here is selecting specific culverts by their IDs for a more focused approach. The Custom feature then generates a report detailing habitat gains by salmon species and overall, along with the estimated cost of the plan.
Demo
- Introduction This section can be used to describe potential use cases.
Learn
Overview
The Learn feature is your comprehensive resource for understanding Upstream. It offers detailed background information about the app, insights into its development, and helpful guidance on how to navigate and utilize its features effectively.
Getting Started
To complement this user manual, we are developing a video tutorial that will provide a visual and interactive guide to Upstream. Your feedback is invaluable to us, so please don’t hesitate to reach out with suggestions or questions to further enrich your learning experience.
Development Process
Upstream has been developed through a collaborative process involving state, tribal, and federal stakeholders, facilitated by a series of meeting groups. This ongoing engagement ensures the tool evolves with diverse inputs, reflecting a range of perspectives and needs. We continue to refine the tool, valuing the contributions from all participants.
Frequently Asked Questions (FAQ)
Q1: What is Upstream?
A1: Upstream is an R Shiny application designed for barrier culvert restoration planning in Western Washington. It offers tools to visualize, plan, and optimize restoration projects.
Q2: Who can benefit from using Upstream?
A2: Upstream is beneficial for environmental planners, ecologists, government agencies, and anyone involved in habitat restoration and environmental conservation, particularly in the context of barrier culverts.
Q3: How do I access Upstream?
A3: Upstream can be accessed online at Upstream’s website. It’s a web-based application, so no download is necessary although it is available as the application is packaged.
Q4: What are the main features of Upstream?
A4: Upstream includes several key features: Explore, Suggest, Custom, and Learn. Each offers different functionalities for data visualization, restoration planning, and educational resources.
Q5: How does the Explore feature work?
A5: The Explore feature allows users to visualize and analyze culvert attributes across different administrative and hydrological boundaries, providing insights into potential restoration areas while taking into account connectivity.
Q6: What is the Suggest feature?
A6: The Suggest feature generates tailored restoration plans based on user-defined constraints, such as budget and project area, maximizing habitat restoration impact.
Q7: Can I create a custom restoration plan with Upstream?
A7: Yes, the Custom feature enables users to select specific culverts and set parameters like budget and project area for targeted restoration planning.
Q8: Are there any resources for learning how to use Upstream?
A8: The Learn feature provides comprehensive resources, including detailed background information, development insights, and a forthcoming video tutorial.
Q9: Is there any support available for Upstream users?
A9: Users can reach out via the contact information provided on the Upstream website for support, feedback, or any queries related to the application.
Project Team
Sunny Jardine (Project lead, Lead developer)
Robby Fonner (Project advisor)
Dan Holland (Project advisor)
Mark Scheuerell (Project advisor)
Braeden Van Deynze (Project advisor)
Connor Lewis Smith (Developer, IT)
Jeffery Comnick (Developer)
Logan Blair (Developer)
J Kahn (Developer)
Zephyr Pfotenhauer (Illustrator)
Additional Information
In the realm of fish barrier culvert management and prioritization, a wealth of resources and methodologies exist to guide decision-making processes. Two key resources provide invaluable insights into these practices:
WDFW Fish Passage Inventory, Assessment, and Prioritization Manual: This comprehensive manual, developed by the Washington Department of Fish and Wildlife (WDFW), outlines detailed schemes for prioritizing fish barrier culverts. It serves as a critical guide for understanding the criteria and processes involved in assessing and prioritizing culvert projects for fish passage restoration. The manual can be accessed here. It is an essential read for anyone involved in fish passage improvement projects, offering a structured approach to prioritizing interventions based on ecological and logistical considerations.
Approaches to Prioritization in the Case Area: A manuscript available on bioRxiv here provides a detailed analysis of different entities’ approaches to prioritization within the case area. This paper offers a comparative perspective, highlighting the diverse methodologies and strategies employed by various organizations in addressing fish passage barriers.
Data and Resources
Comprehensive Data Sources
Upstream utilizes a variety of data sources to provide accurate and up-to-date information. Below is a list of these sources, detailing their specific contributions to our app.
Culvert (Points) Data
-
Last updated for app use: 9/1/23.
Removal of natural barriers and barriers upstream of natural barriers: This dataset has been refined to exclude natural barriers, focusing solely on man-made obstructions to provide a more targeted approach for restoration and management efforts.
Comprehensive Data Collection: Includes detailed information on the location, type, and status of each man-made barrier, aiding in effective planning and prioritization.
Additional details and web maps available here: Offers an interactive way to explore and understand the data, enhancing user engagement and comprehension.
WSDOT Planned and Corrected Barrier Inventories:
Includes Fish Passage Delivery Plan Sites for 2021-2023, 2023-2025, and 2025-2027: Provides a forward-looking view of planned restoration activities, helping users to align their projects with state initiatives.
Statewide data on corrected barriers: This dataset offers insights into the progress made in barrier correction, serving as a benchmark for future projects.
Accessible and User-Friendly Data: The dataset is available in a user-friendly format, making it easier for practitioners and researchers to analyze and utilize.
Explore the dataset here: Direct link to the dataset for in-depth exploration and analysis.
Streams (Lines) Data
-
NHDPlus HR is a comprehensive set of digital spatial data that includes high-resolution flowline networks, catchment areas, and watershed boundaries (WBD HUC). It represents a significant advancement in the mapping and management of water features across the United States.
This dataset is crucial for hydrological analysis, environmental planning, and resource management. It provides detailed information about stream networks, including their flow direction and connectivity.
Data for this project is acquired using nhdplusTools, a suite of tools designed to facilitate the use and analysis of NHDPlus data. These tools help in extracting, processing, and visualizing hydrographic data effectively.
Note on Accuracy and Ongoing Work: While NHDPlus HR offers detailed and extensive hydrographic data, it’s important to acknowledge that these stream lines may not always perfectly represent on-ground realities. To enhance accuracy, ongoing work is exploring the integration of LiDAR-derived stream lines. LiDAR technology, known for its precision in topographical mapping, can provide more accurate representations of stream paths by incorporating elevation data. This effort is part of our continuous commitment to improving data quality and reliability.
Temperature and Land Use Data
Temperature data utilized in our application are derived from the NHDPlusV2 dataset as the August Mean Temperatures in Celsius. The choice of August data is strategic, as it likely represents the maximum average monthly temperatures that anadromous species might encounter. These temperature values are sourced from the PRISM Climate Group (<http://www.prismclimate.org>) for the period spanning 1971 to 2000. For a comprehensive understanding of the attributes in NHDPlusV2, please refer to the NHDPlusV2 User Guide. In cases where temperature data were missing, we applied Inverse Distance Weighting (IDW) interpolation, with a maximum neighbor count of 10, incorporating the bankfull width of water bodies.
Land use data is derived from the National Landcover Dataset, specifically the 2021 version, offering insights into the surrounding environments of habitats. These land types, following the Anderson Land Cover Classification System are further simplified assigning classes 81 and 82 to “agriculture” and classes 21, 22, and 23 to “urban”. All remaining classes then become categorized as “natural”.
Cost Estimates
-
- Provides modelled cost estimates for project planning. These costs were originally estimated in 2019 USD, however, costs are adjusted for inflation during the data compilation process.
Legal Boundaries
App Development and Source Code
Golem Framework: The Upstream app was developed using the Golem Shiny application framework. Golem provides a structured and efficient approach for building complex Shiny applications, enhancing maintainability and scalability.
Source Code on GitHub: The source code for Upstream is available on GitHub, promoting transparency and collaboration within the community. This open-source approach allows users to review, contribute, or adapt the code for their own projects.